Get My Offers [Version 3]

This API enables users to choose whether to retrieve information on the offers attached to their account or retrieve information on offers attached to a sub-account.

Version 3 of this API provides this additional information:

  • Creation of a new Plan-type Rate offer

  • Linked offer(s) information

  • Rate-type offer(s) Plan Cost settings

  • Renewal date comprehensive information

  • Expiration date comprehensive information

HTTP URL

 

GET

/api/v3/customer/{id}/offer/my-offers

Customer {id} can be either the user's own customer ID or one of the customer sub-account ID:

  • Own customer ID: Retrieved information of all offers which were created and attached (allocated) to my account.
  • Sub customer ID: Retrieved information of all offers which were created and attached (allocated) to this given sub account.

Eligibility

The requester is eligible to request information on individual offers attached to them by their parent customer or on individual offers linked to sub-account subscribers.

API Request

This API has no request structure.

API Response

Response Structure

Parameter

Type

M/O/CM

Description

errorCode

String

O

Failure code.

errorMessage

String

O

Failure message.

content

Object

O

Array of main response body object displayed when an API call was successful. For a failure, it will be empty.

pageable

Object

O

Paging information object displayed when an API call was successful. For a failure, it will be empty.

Content data objects

Element

Type

M/O/CM

Description

id

UUID

M

Offer ID

name

String

M

Offer name

description

String

O

Offer description

type

String

M

Individual offer type.

ENUM: RATE, MONEY, USAGE, POOL

cost

Decimal

M

Cost of the offer. May contain a decimal value. If no cost is applied, send 0 (zero).

POOL plan type definitions:

  • FIXED: Cost of the offer, as like all other offer types

  • ACCUMULATIVE: Cost that is added with every added subscriber

currency

String

M

Cost currency, such as USD, GBP, EUR.

creationTime

DateTime

M

Offer creation timestamp

renewalInterval

String

M

Renewal period interval.

ENUM valid values: DAILY, WEEKLY, MONTHLY, QUARTERLY, SEMI_ANNUALLY, ANNUALLY, ONE_TIME

renewalIntervalMethod

String

CM

Determines how to set the renewal day.

ENUM valid values:

  • FIRST_DAY: Renewal day will be the first day of the renewal interval, for example, first of the month per MONTHLY interval.

  • SELF_DEFINED: Renewal day will be the day defined by the user, for example, 10th of the month per MONTHLY interval.

  • PLAN_ALLOCATION: Renewal day will be set based on the actual plan allocation (attachment) day.

  • Empty for ONE_TIME renewal interval

renewalIntervalDay

Numeric

CM

Determines the renewal day of the selected period.

ENUM valid values:

  • DAILY: N/A

  • WEEKLY: 1–7

  • MONTHLY: 1–28

  • QUARTERLY: 1–90

  • SEMI_ANNUALLY: 1–180

  • ANNUALLY: 1–365

ONE_TIME: N/A

Populated only if SELF_DEFINED or FIRST_DAY has been set for the renewalIntervalMethod attribute.

expirationType

String

O

Determines how to set the expiration date.

ENUM valid values:

  • FIXED: Fixed, predefined expiration date.

  • RELATIVE_ATTACHED: Time duration from the moment the plan was attached to the subscriber (SIM), for example, 10 days.

  • RELATIVE_FIRST_USE: Time duration from the time the plan was first used by the subscriber, for example 10 days.

If not sent, the plan will not expire at all.

expirationDate

Date

CM

Determines the requested date as per the selected expirationType.

  • Populated only if the expirationType parameter has been set to FIXED.

  • Empty for other expirationType settings or no expiration type.

expirationUnit

String

CM

Determines the time unit that should be used for expiration calculation.

ENUM valid values: DAY, WEEK, MONTH, YEAR

Empty if the selected expirationType is FIXED or no expiration type.

expirationValue

Numeric

CM

Determines the requested time value as per the selected expirationUnit.

Empty if the selected expirationType is FIXED or no expiration type.

isProrated

Boolean

M

Plan proration.

  • True = Proration will be calculated when attaching this plan

  • False = There is no proration

A Pool plan is always False.
isIncludingAccessFee

Boolean

M

Specifies if the offer price already includes inherent access fee and surcharge fee.

  • True – Offer price includes access\surcharge fees. Once a calendar month, when registering on the network, the system will not charge additionally on top of the offer price.

  • False – Offer price does not include access\surcharge fee. Once a calendar month, when registering on the network, the system will charge the access\surcharge fees in addition to the offer price.

money

Object

CM

Money type object.

Populated when MONEY offer type is returned

Empty if a RATE, USAGE or POOL offer type is returned

rate

Object

CM

Rate typeobject.

  • Populated when RATE offer type is returned

  • Empty if a USAGE, MONEY or POOL offer type is returned

usage

Object

CM

Usage type object.

Populated when a USAGE offer type is populated

Empty if a RATE, MONEY or POOL offer type is returned

pool

Object

CM

Pool plan type object.

Populated whena POOL offer type is returned

Empty if any other offer type is returned (USAGE, RATE, MONEY).

availabilityZone

Object

O

Array of availability zones object that are assigned to this plan.

Empty array means that the plan is available in any zone.

linkedOffers

Object

O

Array of offer(s) object linked to this offer. The order of the instances in the array determines their priority for charging.

An Empty array means that the created offer has no linked offers.

Money data objects

Element

Type

M/O/CM

Description

activationType

String

M

Displays plan activation behavior.

Valid values:

REGULAR

FIRSTEVENT_PERIODIC

FIRST_EVENT_NON_PERIODIC

Rate data objects

Element

Type

M/O/CM

Description

type

String

M

Rate offer type.

ENUM valid values: ACCOUNT, PLAN_FIXED, PLAN_CUSTOMIZED

dataLimit

Decimal

O

Displays the maximal allowed DATA usage consumption.

dataLimitUnitType

String

CM

Data limit unit type. Valid values: KB, MB, GB

Populated when data limit exists.

smsLimit

Decimal

O

Displays the maximal allowed SMS usage consumption. Unit counting is always a ‘unit’.

Usage data objects

Element

Type

M/O/CM

Description

activationType

String

M

Displays plan activation behavior.

Valid values:

  • REGULAR

  • FIRSTEVENT_PERIODIC

  • FIRST_EVENT_NON_PERIODIC

usageType

Object

M

Array of usage types object.

Usage Type data objects

Element

Type

M/O/CM

Description

type

String

M

Type of the usage. Valid values: DATA, SMS

value

Decimal

M

Overall allowance value for regular offer or for FIXED-type Pool Plan.

  • Allowance value per every added subscriber for ACCUMULATIVE-type Pool Plan.

  • Data consumption for DATA type.

  • Unit counting for SMS type.

unitType

String

CM

  • Usage unit type = DATA

  • Valid values: KB, MB, GB.

Populated when usage type is set to DATA.

Pool data objects

Element

Type

M/O/CM

Description

type

String

M

Pool plan type. Valid values: FIXED, ACCUMULATIVE

activationType

String

M

Defines pool plan activation behavior.

Valid values:

  • REGULAR

  • FIRSTEVENT_PERIODIC

  • FIRST_EVENT_NON_PERIODIC

poolusageType

Object

M

Array of (pool) usage types object.

Pool Usage Type data objects

Element

Type

M/O/CM

Description

type

String

M

Type of the usage.

ENUM valid values: DATA, SMS

value

Decimal

M

Allowance value.

Data consumption for DATA type.

Unit counting for SMS type.

unitType

String

CM

Usage unit type = DATA

ENUM valid values: KB, MB, GB

Mandatory for DATA usage type. Empty for SMS usage type.

Ignored if populated for SMS usage type.

limitValue

Decimal

O

Defines usage limit value.

Data consumption for DATA type.

Unit counting for SMS type.

limitUnitType

String

CM

Limit unit type = DATA

ENUM valid values: KB, MB, GB

Mandatory when setting the limit for DATA usage. Empty for SMS usage type.

Ignored if populated for SMS usage type.

Availability Zone data objects

Element

Type

M/O/CM

Description

id

UUID

M

Universal unique ID of the customer's availability zones.

name

String

M

Customer's availability zone name.

Linked Offers data objects

Element

Type

M/O/CM

Description

id

UUID

M

Universal unique ID of the offer to link to this offer.

isPinned

Boolean

O

[Future Feature]

Denotes whether or not the linked offer can be removed from the parent offer.

True = Linked offer is fixed and cannot be removed.

False = Linked offer is not fixed and can be removed

Pageable data objects

Element

Type

M/O/CM

Description

page

Numeric

M

Page number

size

Numeric

M

Page size. Number of requested elements per page

totalPages

Numeric

M

Total amount of available pages per requested page size

totalElements

Numeric

M

Total amount of retrieved elements

Error Codes

In addition to the general success and failure codes, the following error codes are possible.

Code

Message

GLOBAL_1001

Service unavailable. Please try again

CUSTOMER_1002

Customer does not exist

CUSTOMER_1006

Failed to retrieve customer details

Examples

Request Body

Copy 
{
}

Response Body: Regular Plan (Money) Success ACK

Copy 
{
  "errorCode": "",
  "errorMessage": "",
  "content": [
    {
      "id": "e7fcef24-5c03-41dd-9e33-995b7d6f47a7",
      "name": "roaming",
      "description": "roaming bundle",
      "type": "MONEY",
      "creationTime": "2020-07-01T00:00:00.977Z",
      "expirationTime": "2020-07-31T00:59:09.977Z",
      "renewalInterval": "MONTHLY",
      "isProrated": true,
      "isIncludingAccessFee": false,
      "availabilityZone": [
        {
          "id": "1b15048b-1ed4-4d34-a074-c7e26520e12a",
          "name": "North America 05"
        }
      ],
      "money": [
        {
          "value": 300,
          "currency": "USD",
          "activationType": "REGULAR"
        }
      ]
    },
    {
      "id": "ff74dca6-8e7f-4b85-a42b-13860913b370",
      "name": "regular",
      "description": "regular bundle",
      "type": "MONEY",
      "creationTime": "2020-07-01T00:00:00.977Z",
      "expirationTime": "2020-07-31T00:59:09.977Z",
      "renewalInterval": "MONTHLY",
      "isProrated": true,
      "availabilityZone": [],
      "money": [
        {
          "value": 100,
          "currency": "GBP",
          "activationType": "REGULAR"
        }
      ]
    }
  ],
  "pageable": {
    "page": 1,
    "size": 10,
    "totalPages": 1,
    "totalElements": 2
  }
}

Response Body: Pool Plan Success ACK

Copy 
{
  "errorCode": "",
  "errorMessage": "",
  "content": [
    {
      "id": "e7fcef24-5c03-41dd-9e33-995b7d6f47a7",
      "name": "family 50GB+",
      "description": "family bundle",
      "type": "POOL",
      "creationTime": "2020-07-01T00:00:00.977Z",
      "expirationTime": "2020-07-31T00:59:09.977Z",
      "renewalInterval": "MONTHLY",
      "isProrated": false,
      "isIncludingAccessFee": false,
      "availabilityZone": [
        {
          "id": "1b15048b-1ed4-4d34-a074-c7e26520e12a",
          "name": "North America 05"
        }
      ],
      "pool": [
        {
          "type": "FIXED",
          "cost": 15,
          "currency": "USD",
          "activationType": "REGULAR",
          "usageType": [
            {
              "type": "DATA",
              "value": 50,
              "unitType": "GB",
              "limitValue": 20,
              "limitUnitType": "GB"
            },
            {
              "type": "SMS",
              "value": 100,
              "unitType": "",
              "limitValue": 10,
              "limitUnitType": ""
            }
          ]
        }
      ]
    }
  ],
  "pageable": {
    "page": 1,
    "size": 10,
    "totalPages": 1,
    "totalElements": 2
  }
}

Response Body: Failure NAK

Copy 
{
  "errorCode": "GLOBAL_1001",
  "errorMessage": "Service unavailable. Please try again",
  "content": "",
  "pageable": ""
}